gtk: fix annotation syntax and missing some missing annotations

These changes clean up various errors and omissions resulting from
either slightly incorrect G-I/gtk-doc syntax or missing documentation
blocks.

https://bugzilla.gnome.org/show_bug.cgi?id=730745

diff --git a/gtk/a11y/gtkcontainercellaccessible.c b/gtk/a11y/gtkcontainercellaccessible.c
index ea8ada0767f2c21fb40b30406d3a2f593a7b2ad3..4c2c80409a61da7bbdd3c396b815baae6615334a 100644 (file)
--- a/gtk/a11y/gtkcontainercellaccessible.c
+++ b/gtk/a11y/gtkcontainercellaccessible.c
@@ -162,6 +162,14 @@ gtk_container_cell_accessible_remove_child (GtkContainerCellAccessible *containe
   g_object_unref (child);
 }
 
+/**
+ * gtk_container_cell_accessible_get_children:
+ * @container: the container
+ *
+ * Get a list of children.
+ *
+ * Returns: (transfer none) (element-type Gtk.CellAccessible)
+ */
 GList *
 gtk_container_cell_accessible_get_children (GtkContainerCellAccessible *container)
 {

diff --git a/gtk/a11y/gtktoplevelaccessible.c b/gtk/a11y/gtktoplevelaccessible.c
index 037500b066b56d5145bdf92ab7e2bfe07eeb170b..b767667b30c43a013a14ddea49f89b3ed98269ac 100644 (file)
--- a/gtk/a11y/gtktoplevelaccessible.c
+++ b/gtk/a11y/gtktoplevelaccessible.c
@@ -298,6 +298,12 @@ gtk_toplevel_accessible_init (GtkToplevelAccessible *toplevel)
                               hide_event_watcher, toplevel, (GDestroyNotify) NULL);
 }
 
+/**
+ * gtk_toplevel_accessible_get_children:
+ *
+ * Returns: (transfer none) (element-type Gtk.Window): List of
+ *   children.
+ */
 GList *
 gtk_toplevel_accessible_get_children (GtkToplevelAccessible *accessible)
 {

diff --git a/gtk/deprecated/gtkcolorsel.h b/gtk/deprecated/gtkcolorsel.h
index 21f86b6b1ffafbeeb7bb4b0d441faa39d489365e..3ac863784ffc664d7121079ee2983d1be75a7f77 100644 (file)
--- a/gtk/deprecated/gtkcolorsel.h
+++ b/gtk/deprecated/gtkcolorsel.h
@@ -74,7 +74,7 @@ struct _GtkColorSelection
 {
   GtkBox parent_instance;
 
-  /* < private_data > */
+  /*< private >*/
   GtkColorSelectionPrivate *private_data;
 };
 

diff --git a/gtk/deprecated/gtkstyle.c b/gtk/deprecated/gtkstyle.c
index 6b759deea0d9ed794f4b0e1fa6907cdc1a78f6d3..03e27e8f623f7a00618f8918c912d7e01e347276 100644 (file)
--- a/gtk/deprecated/gtkstyle.c
+++ b/gtk/deprecated/gtkstyle.c
@@ -4077,7 +4077,7 @@ gtk_widget_get_default_style (void)
  *
  * Since: 2.20
  *
- * Deprecated: 3.0. This step is unnecessary with #GtkStyleContext.
+ * Deprecated: 3.0: This step is unnecessary with #GtkStyleContext.
  **/
 void
 gtk_widget_style_attach (GtkWidget *widget)
@@ -4514,7 +4514,7 @@ gtk_widget_modify_base (GtkWidget      *widget,
  *
  * Since: 2.12
  *
- * Deprecated: 3.0. Use gtk_widget_override_cursor() instead.
+ * Deprecated: 3.0: Use gtk_widget_override_cursor() instead.
  */
 void
 gtk_widget_modify_cursor (GtkWidget      *widget,

diff --git a/gtk/gtkclipboard.h b/gtk/gtkclipboard.h
index f7d27d73b0791016a1aecf223ccd764949b5a34e..13f7f7bffb447b4dfc58b6131d5a9cb31a377347 100644 (file)
--- a/gtk/gtkclipboard.h
+++ b/gtk/gtkclipboard.h
@@ -62,6 +62,22 @@ typedef void (* GtkClipboardTextReceivedFunc)     (GtkClipboard     *clipboard,
                                                   const gchar      *text,
                                                   gpointer          data);
 
+/**
+ * GtkClipboardRichTextReceivedFunc:
+ * @clipboard: the #GtkClipboard
+ * @format: The format of the rich text
+ * @text: (nullable) (type utf8): the rich text received, as
+ *   a UTF-8 encoded string, or %NULL if retrieving the data failed.
+ * @length: Length of the text.
+ * @data: (closure): the @user_data supplied to
+ *   gtk_clipboard_request_rich_text().
+ *
+ * A function to be called when the results of
+ * gtk_clipboard_request_rich_text() are received, or when the request
+ * fails.
+ *
+ * Since: 2.10
+ */
 typedef void (* GtkClipboardRichTextReceivedFunc) (GtkClipboard     *clipboard,
                                                    GdkAtom           format,
                                                   const guint8     *text,
@@ -84,6 +100,19 @@ typedef void (* GtkClipboardImageReceivedFunc)    (GtkClipboard     *clipboard,
                                                   GdkPixbuf        *pixbuf,
                                                   gpointer          data);
 
+/**
+ * GtkClipboardURIReceivedFunc:
+ * @clipboard: the #GtkClipboard
+ * @uris: (array zero-terminated=1): the received URIs
+ * @data: (closure): the @user_data supplied to
+ *   gtk_clipboard_request_uris().
+ *
+ * A function to be called when the results of
+ * gtk_clipboard_request_uris() are received, or when the request
+ * fails.
+ *
+ * Since: 2.14
+ */
 typedef void (* GtkClipboardURIReceivedFunc)      (GtkClipboard     *clipboard,
                                                   gchar           **uris,
                                                   gpointer          data);

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index cf0505fd27daae79249ad6a7c753399dd4cad539..1aafe8128bd01fbabeaec303d71cf2b18374d168 100644 (file)
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -1419,7 +1419,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    * request, the margin will be added in addition to the size from
    * gtk_widget_set_size_request() for example.
    *
-   * Deprecated: 3.12. Use #GtkWidget:margin-start instead.
+   * Deprecated: 3.12: Use #GtkWidget:margin-start instead.
    *
    * Since: 3.0
    */
@@ -1442,7 +1442,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    * request, the margin will be added in addition to the size from
    * gtk_widget_set_size_request() for example.
    *
-   * Deprecated: 3.12. Use #GtkWidget:margin-end instead.
+   * Deprecated: 3.12: Use #GtkWidget:margin-end instead.
    *
    * Since: 3.0
    */
@@ -1821,7 +1821,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    * The ::state-changed signal is emitted when the widget state changes.
    * See gtk_widget_get_state().
    *
-   * Deprecated: 3.0. Use #GtkWidget::state-flags-changed instead.
+   * Deprecated: 3.0: Use #GtkWidget::state-flags-changed instead.
    */
   widget_signals[STATE_CHANGED] =
     g_signal_new (I_("state-changed"),
@@ -7820,7 +7820,7 @@ gtk_widget_reparent_fixup_child (GtkWidget *widget,
  * Moves a widget from one #GtkContainer to another, handling reference
  * count issues to avoid destroying the widget.
  *
- * Deprecated: 3.14. Use gtk_container_remove() and gtk_container_add().
+ * Deprecated: 3.14: Use gtk_container_remove() and gtk_container_add().
  **/
 void
 gtk_widget_reparent (GtkWidget *widget,
@@ -8784,7 +8784,7 @@ gtk_widget_get_state_flags (GtkWidget *widget)
  * of a widget (insensitive, prelighted, etc.) Usually you should set
  * the state using wrapper functions such as gtk_widget_set_sensitive().
  *
- * Deprecated: 3.0. Use gtk_widget_set_state_flags() instead.
+ * Deprecated: 3.0: Use gtk_widget_set_state_flags() instead.
  **/
 void
 gtk_widget_set_state (GtkWidget           *widget,
@@ -8839,7 +8839,7 @@ gtk_widget_set_state (GtkWidget           *widget,
  *
  * Since: 2.18
  *
- * Deprecated: 3.0. Use gtk_widget_get_state_flags() instead.
+ * Deprecated: 3.0: Use gtk_widget_get_state_flags() instead.
  */
 GtkStateType
 gtk_widget_get_state (GtkWidget *widget)